init by dreamchaserxzq · Pull Request #58 · code-mphi/ECOGEN

dreamchaserxzq · 2026-03-05T05:49:40Z

init

Add a Chinese markdown study guide summarizing the ECOGEN C++ code structure and key modules.

…or-ecogen-c++-source Add Chinese C++ source study guide

Add detailed reading guidance for core components including Run, Cell, Model, Eos, mesh, boundary conditions, high-order reconstruction, add-physics, sources, relaxations, and parallel communications.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…urce-2ka4dc

…or-ecogen-c++-source-2ka4dc docs: expand C++ source study guide with component-level reading guidance

Copilot

Pull request overview

This PR adds a new documentation file docs/ECOGEN_Cpp_Source_Study.md that serves as a Chinese-language source code study guide for the ECOGEN C++ CFD platform. The document provides a structural walkthrough of the codebase, covering the main entry point, the Run orchestration class, input/output, physical models, mesh handling, parallel communication, and other key modules.

Changes:

Added a 179-line Chinese-language Markdown document that maps out the ECOGEN source code architecture, module responsibilities, and suggested reading order for developers.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-05T05:54:07Z

docs/ECOGEN_Cpp_Source_Study.md

+ECOGEN 是一个面向可压缩多相流的 CFD 平台，采用 C++ 面向对象设计，官方 README 给出了项目定位与外部文档入口（用户文档与 API 文档）。【F:README.md†L1-L14】
+
+从构建层面看，`CMakeLists.txt` 将 `src` 下的所有 `*.cpp` 作为可执行文件的源代码，项目名为 `ECOGEN`，强制使用 C++11，并依赖 MPI。【F:CMakeLists.txt†L1-L36】
+
+**结构总览（以源码目录为核心）：**
+- `src/`：主要 C++ 源码与模块目录（核心逻辑）。【F:CMakeLists.txt†L27-L36】
+- `libEOS/`、`libMeshes/`、`libTests/` 等：配套库与测试资源（详细内容需按需深入）。
+- `docs/`：现有文档与生成的 API/手册。
+
+> 本学习文档重点聚焦 `src/` 的核心结构与主流程。
+
+## 2. 入口与主流程：`main.cpp`
+
+`main.cpp` 是程序入口，负责：
+- 初始化 MPI；
+- 解析 `ECOGEN.xml` 主配置文件；
+- 遍历 `testCase` 列表逐个执行；
+- 每个测试用例通过 `Run` 生命周期：`initialize()` → `solver()` → `finalize()`；
+- 捕获输入异常与运行时异常，并进行输出和清理。【F:src/main.cpp†L33-L154】
+
+关键流程片段：
+1. MPI 初始化与 rank/size 获取。【F:src/main.cpp†L49-L57】
+2. 通过 `tinyxml2` 解析 `ECOGEN.xml` 并定位 `<testCase>` 列表。【F:src/main.cpp†L65-L99】
+3. 对每个 `testCase`：构造 `Run`，执行 `initialize/solver/finalize`。【F:src/main.cpp†L90-L117】
+4. 错误处理分为输入异常与运行时异常，分别处理与释放资源。【F:src/main.cpp†L121-L153】


The citation format 【F:file†Lx-Ly】 used throughout the document is non-standard and the line numbers are frequently inaccurate. For example:

【F:src/main.cpp†L121-L153】 suggests error handling is at lines 121-153, but the catch blocks actually span lines 112-139.

【F:src/main.cpp†L49-L57】 refers to MPI init at lines 49-57, but MPI initialization is actually at lines 54-57 (lines 49-51 are error redirection setup).

【F:src/Parallel/Parallel.h†L113-L120】 claims to reference rankCpu/Ncpu, but these are actually at lines 166-167 (line 113 extends into private members).

【F:src/Parallel/Parallel.h†L29-L120】 implies the class ends at line 120, but the Parallel class extends to line 163 and the file has 170 lines.

These annotations appear to be AI-generated markers that are not part of any project convention. They should either be removed entirely or replaced with accurate, human-verified references. Inaccurate line references will mislead readers trying to navigate the source code.

Copilot · 2026-03-05T05:54:07Z

docs/ECOGEN_Cpp_Source_Study.md

+- `MeshUnStruct`（含 Gmsh 读取支持）
+
+### 5.2 物理模型（Models）
+`Models/HeaderModel.h` 注册多种模型（Euler、PUEq、Korteweg 等），并提供扩展入口。【F:src/Models/HeaderModel.h†L33-L43】


Section 5.2 mentions models "Euler、PUEq、Korteweg 等" but HeaderModel.h also registers EulerHomogeneous, PTUEq, UEq, UEqTotEnergy, and NonLinearSchrodinger. The document omits several models while claiming to describe what the header registers. This could mislead readers about the available models.

Suggested change

`Models/HeaderModel.h` 注册多种模型（Euler、PUEq、Korteweg 等），并提供扩展入口。【F:src/Models/HeaderModel.h†L33-L43】

`Models/HeaderModel.h` 注册多种物理模型（如 Euler、EulerHomogeneous、PUEq / PTUEq、UEq / UEqTotEnergy、Korteweg、NonLinearSchrodinger 等），并提供扩展入口。【F:src/Models/HeaderModel.h†L33-L43】

Copilot · 2026-03-05T05:54:07Z

docs/ECOGEN_Cpp_Source_Study.md

+# ECOGEN C++ 源码学习文档（结构与内容导读）
+
+> 目标：帮助你快速建立“ECOGEN C++ 源码结构 + 运行主流程 + 关键模块职责”的整体认知，为后续深入阅读与二次开发打基础。
+
+## 1. 项目定位与总体结构
+
+ECOGEN 是一个面向可压缩多相流的 CFD 平台，采用 C++ 面向对象设计，官方 README 给出了项目定位与外部文档入口（用户文档与 API 文档）。【F:README.md†L1-L14】
+
+从构建层面看，`CMakeLists.txt` 将 `src` 下的所有 `*.cpp` 作为可执行文件的源代码，项目名为 `ECOGEN`，强制使用 C++11，并依赖 MPI。【F:CMakeLists.txt†L1-L36】
+
+**结构总览（以源码目录为核心）：**
+- `src/`：主要 C++ 源码与模块目录（核心逻辑）。【F:CMakeLists.txt†L27-L36】
+- `libEOS/`、`libMeshes/`、`libTests/` 等：配套库与测试资源（详细内容需按需深入）。
+- `docs/`：现有文档与生成的 API/手册。
+
+> 本学习文档重点聚焦 `src/` 的核心结构与主流程。
+
+## 2. 入口与主流程：`main.cpp`
+
+`main.cpp` 是程序入口，负责：
+- 初始化 MPI；
+- 解析 `ECOGEN.xml` 主配置文件；
+- 遍历 `testCase` 列表逐个执行；
+- 每个测试用例通过 `Run` 生命周期：`initialize()` → `solver()` → `finalize()`；
+- 捕获输入异常与运行时异常，并进行输出和清理。【F:src/main.cpp†L33-L154】
+
+关键流程片段：
+1. MPI 初始化与 rank/size 获取。【F:src/main.cpp†L49-L57】
+2. 通过 `tinyxml2` 解析 `ECOGEN.xml` 并定位 `<testCase>` 列表。【F:src/main.cpp†L65-L99】
+3. 对每个 `testCase`：构造 `Run`，执行 `initialize/solver/finalize`。【F:src/main.cpp†L90-L117】
+4. 错误处理分为输入异常与运行时异常，分别处理与释放资源。【F:src/main.cpp†L121-L153】
+
+## 3. 核心调度类：`Run`
+
+`Run` 是一次模拟的中心对象，聚合了**网格、物理模型、流体状态、IO、时间推进、额外物理、源项、并行通信**等关键组件。【F:src/Run.h】
+
+### 3.1 `Run` 的职责
+- **初始化**：读入输入文件、创建网格与物理模型、初始化状态等。
+- **求解**：包含双曲项、额外物理、源项、松弛等过程（由内部函数分层调用）。【F:src/Run.h】
+- **收尾**：释放资源、整理输出。


This document is written entirely in Chinese, whereas all existing project documentation (README.md, README_Developer.md, Sphinx docs, Doxygen comments, code comments) is consistently written in English. Adding a Chinese-only document breaks the language consistency of the project's documentation. This should be translated to English to match the project's convention.

Suggested change

# ECOGEN C++ 源码学习文档（结构与内容导读）

> 目标：帮助你快速建立“ECOGEN C++ 源码结构 + 运行主流程 + 关键模块职责”的整体认知，为后续深入阅读与二次开发打基础。

## 1. 项目定位与总体结构

ECOGEN 是一个面向可压缩多相流的 CFD 平台，采用 C++ 面向对象设计，官方 README 给出了项目定位与外部文档入口（用户文档与 API 文档）。【F:README.md†L1-L14】

从构建层面看，`CMakeLists.txt` 将 `src` 下的所有 `*.cpp` 作为可执行文件的源代码，项目名为 `ECOGEN`，强制使用 C++11，并依赖 MPI。【F:CMakeLists.txt†L1-L36】

**结构总览（以源码目录为核心）：**

- `src/`：主要 C++ 源码与模块目录（核心逻辑）。【F:CMakeLists.txt†L27-L36】

- `libEOS/`、`libMeshes/`、`libTests/` 等：配套库与测试资源（详细内容需按需深入）。

- `docs/`：现有文档与生成的 API/手册。

> 本学习文档重点聚焦 `src/` 的核心结构与主流程。

## 2. 入口与主流程：`main.cpp`

`main.cpp` 是程序入口，负责：

- 初始化 MPI；

- 解析 `ECOGEN.xml` 主配置文件；

- 遍历 `testCase` 列表逐个执行；

- 每个测试用例通过 `Run` 生命周期：`initialize()` → `solver()` → `finalize()`；

- 捕获输入异常与运行时异常，并进行输出和清理。【F:src/main.cpp†L33-L154】

关键流程片段：

1. MPI 初始化与 rank/size 获取。【F:src/main.cpp†L49-L57】

2. 通过 `tinyxml2` 解析 `ECOGEN.xml` 并定位 `<testCase>` 列表。【F:src/main.cpp†L65-L99】

3. 对每个 `testCase`：构造 `Run`，执行 `initialize/solver/finalize`。【F:src/main.cpp†L90-L117】

4. 错误处理分为输入异常与运行时异常，分别处理与释放资源。【F:src/main.cpp†L121-L153】

## 3. 核心调度类：`Run`

`Run` 是一次模拟的中心对象，聚合了**网格、物理模型、流体状态、IO、时间推进、额外物理、源项、并行通信**等关键组件。【F:src/Run.h】

### 3.1 `Run` 的职责

- **初始化**：读入输入文件、创建网格与物理模型、初始化状态等。

- **求解**：包含双曲项、额外物理、源项、松弛等过程（由内部函数分层调用）。【F:src/Run.h】

- **收尾**：释放资源、整理输出。

# ECOGEN C++ Source Code Study Guide (Structure and Content Overview)

> Goal: Help you quickly build an overall understanding of the "ECOGEN C++ source code structure + main execution flow + responsibilities of key modules" as a foundation for deeper reading and further development.

## 1. Project Positioning and Overall Structure

ECOGEN is a CFD platform for compressible multiphase flows, designed with object-oriented C++. The official README describes the project's positioning and provides entry points to external documentation (user documentation and API documentation).【F:README.md†L1-L14】

From the build perspective, `CMakeLists.txt` treats all `*.cpp` files under `src` as the sources of the executable, with the project named `ECOGEN`, enforcing C++11 and depending on MPI.【F:CMakeLists.txt†L1-L36】

**Structural overview (centered on the source tree):**

- `src/`: main C++ source code and module directory (core logic).【F:CMakeLists.txt†L27-L36】

- `libEOS/`, `libMeshes/`, `libTests/`, etc.: supporting libraries and test resources (details can be explored as needed).

- `docs/`: existing documentation and generated API manuals/guides.

> This study guide focuses on the core structure and main execution flow under `src/`.

## 2. Entry Point and Main Flow: `main.cpp`

`main.cpp` is the program entry point and is responsible for:

- initializing MPI;

- parsing the main configuration file `ECOGEN.xml`;

- iterating over the `testCase` list and executing each one;

- running each test case through the `Run` lifecycle: `initialize()` → `solver()` → `finalize()`;

- catching input and runtime exceptions, then handling output and cleanup.【F:src/main.cpp†L33-L154】

Key flow segments:

1. MPI initialization and retrieval of rank/size.【F:src/main.cpp†L49-L57】

2. Parsing `ECOGEN.xml` via `tinyxml2` and locating the `<testCase>` list.【F:src/main.cpp†L65-L99】

3. For each `testCase`: construct a `Run` and execute `initialize/solver/finalize`.【F:src/main.cpp†L90-L117】

4. Error handling is divided into input exceptions and runtime exceptions, with corresponding processing and resource release.【F:src/main.cpp†L121-L153】

## 3. Core Orchestrator Class: `Run`

`Run` is the central object for a single simulation, aggregating key components such as **mesh, physical models, fluid state, I/O, time integration, additional physics, source terms, and parallel communication**.【F:src/Run.h】

### 3.1 Responsibilities of `Run`

- **Initialization**: read input files, create meshes and physical models, and initialize states.

- **Solving**: perform hyperbolic terms, additional physics, source terms, relaxation, etc. (invoked hierarchically via internal functions).【F:src/Run.h】

- **Finalization**: release resources and organize outputs.

dreamchaserxzq and others added 8 commits February 4, 2026 17:19

XX_work: add C++ source study guide

7b549bc

Add a Chinese markdown study guide summarizing the ECOGEN C++ code structure and key modules.

Merge pull request #1 from dreamchaserxzq/codex/create-markdown-doc-f…

1038bf9

…or-ecogen-c++-source Add Chinese C++ source study guide

XX_work: expand source guide details

7e0a9b1

Add detailed reading guidance for core components including Run, Cell, Model, Eos, mesh, boundary conditions, high-order reconstruction, add-physics, sources, relaxations, and parallel communications.

Update docs/ECOGEN_Cpp_Source_Study.md

eeaea47

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/ECOGEN_Cpp_Source_Study.md

79e5948

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/ECOGEN_Cpp_Source_Study.md

e50039d

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Merge branch 'devel' into codex/create-markdown-doc-for-ecogen-c++-so…

14595ef

…urce-2ka4dc

Merge pull request #2 from dreamchaserxzq/codex/create-markdown-doc-f…

557cf12

…or-ecogen-c++-source-2ka4dc docs: expand C++ source study guide with component-level reading guidance

Copilot AI review requested due to automatic review settings March 5, 2026 05:49

Copilot started reviewing on behalf of dreamchaserxzq March 5, 2026 05:50 View session

Copilot AI reviewed Mar 5, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

init#58

init#58
dreamchaserxzq wants to merge 8 commits intocode-mphi:develfrom
dreamchaserxzq:devel

dreamchaserxzq commented Mar 5, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 5, 2026

Uh oh!

Copilot AI Mar 5, 2026

Uh oh!

Copilot AI Mar 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	`Models/HeaderModel.h` 注册多种模型（Euler、PUEq、Korteweg 等），并提供扩展入口。【F:src/Models/HeaderModel.h†L33-L43】
	`Models/HeaderModel.h` 注册多种物理模型（如 Euler、EulerHomogeneous、PUEq / PTUEq、UEq / UEqTotEnergy、Korteweg、NonLinearSchrodinger 等），并提供扩展入口。【F:src/Models/HeaderModel.h†L33-L43】

Conversation

dreamchaserxzq commented Mar 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants